Agent 可观测性
传统 APM 记录的是"一次 HTTP 请求耗时 18.4 秒"。Agent 需要回答的是"这 18.4 秒里调了几次模型、几次工具、每次花了多少 token、钱算在谁头上"。本专题拆解这套数据怎么产生、按什么规范组织、以及怎么落到平台上。
先约定几个词，本专题全程使用：
| 词 | 意思 |
|---|---|
| APM | Application Performance Monitoring，应用性能监控。传统那套「记请求耗时、错误率、吞吐」的工具，Datadog、SkyWalking 都属于这一类 |
| span（跨度） | 一次有起止时间的操作记录，比如「调用了一次模型」「执行了一次工具」 |
| trace（追踪） | 一次完整请求里所有 span 组成的树。Agent 的 trace 是树不是链，因为主 Agent 会调子 Agent、子 Agent 再调工具 |
| 语义约定 | 规定 span 该叫什么名字、带哪些属性的标准。有了它，不同厂商的工具才能读懂同一份数据 —— 这正是 02 篇要讲的东西 |
| 埋点（instrumentation） | 在代码里插入产生 span 的那些调用。埋点决定了你事后能查到什么，是最难改的一层 |
| 成本归因 | 把每一次模型调用的花费算到具体的团队、项目或用户头上。账单只有一张总的，拆开它就是 03 篇的主题 |
一、这一层要解决的三个问题
三者是递进的：没有结构化的 trace 就谈不上规范，没有统一规范就没法跨系统归因。
二、三篇正文
| # | 标题 | 覆盖内容 |
|---|---|---|
| 01 | Agent 的 Trace 长什么样 | 十种操作类型、九个 Agent 专属指标、MCP 的埋点、最小可用清单 |
| 02 | 两套语义约定 | OTel GenAI 与 OpenInference 的覆盖差异、生态站队、如何不选边 |
| 03 | 成本归因与选型 | 归因的四个难点、网关侧打标方案、三个开源平台对比 |
三、一个需要先知道的前提
OpenTelemetry 的 GenAI 语义约定尚未稳定。 截至 2026-08，没有任何一个 gen_ai.* 属性、span 或指标被标记为 Stable —— 该规范中已标记稳定的 128 个属性，全部是从核心语义约定继承来的通用项（server.address、error.type 这类），与 GenAI 无关。
而且它在 2026 年搬过一次家：v1.42.0（2026-06-12）把全部 gen_ai.* 从主仓库拆出，成立独立的 semantic-conventions-genai 仓库（该仓库创建于 2026-05-05）。
这个前提直接影响埋点策略 —— 02 篇会给出应对方式。
四、拆解对象
4.1 两份规范
| 仓库 | ★ | 出身 | 在本专题里的角色 |
|---|---|---|---|
open-telemetry/semantic-conventions-genai | 262 | OpenTelemetry 官方 | gen_ai.* 命名空间的定义者。star 数低是因为使用者 star 的是 SDK 不是规范文本，判断采纳度要看哪些平台实现了它 |
Arize-ai/openinference | 1,154 | Arize（Phoenix 的开发方） | llm.* document.* embedding.* 命名空间。把评测与检索质量当成追踪的一等公民 |
两份规范的逐条对比在 02 篇。
4.2 三个开源平台
| 项目 | ★ | 协议 | 语言 | 定位 |
|---|---|---|---|---|
langfuse/langfuse | 33,369 | NOASSERTION | TypeScript | 全功能 LLM 工程平台，两套约定都映射进自有数据模型 |
Arize-ai/phoenix | 11,105 | NOASSERTION | Python | 本地优先的调试与评测工具，单进程起步 |
traceloop/openllmetry | 7,384 | Apache-2.0 | Python | 只做埋点不做后端，三者中唯一协议明确 |
选型判据在 03 篇。注意前两个 gh api 返回 NOASSERTION，意思是自动识别不出许可证，用之前要自己翻仓库里的 LICENSE。
五、与其他专题的关系
- Agent 网关：网关是可观测数据的主要产生点，也是成本归因最可靠的口径来源
- Agent 持久化执行：重放机制会让同一步在 trace 里出现多次，需要专门处理
- EvalHub 项目沉淀：评测平台对"过程证据"的记录需求与本专题同源
← 回到 Agent Infra 板块总览